24. Projekt zespołowy - tydzień 2 z 3

Code review pozwala nie tylko zachowania spójności kodu i udoskonalanie rozwiązań, ale również na sprawną naukę poprzez wymianę doświadczeń. Dzięki lepszemu poznaniu kodu innych członków zespołu będziesz w stanie lepiej rozumieć projekt oraz poznawać ciekawe sposoby rozwiązywania problemów.

Pewnie nachodzi Cię obawa, że nie czujesz się w kompetencjach, aby oceniać pracę innych osób. Nic bardziej mylnego — w programowaniu analiza rozwiązań jest właśnie tym, co popycha nas do przodu. Jeśli przeprowadzisz sumienne code review, to pomożesz sobie oraz swojemu zespołowi.

Pamiętaj, że chodzi tutaj o pracę zespołową, gdzie chcesz z innymi osobami komfortowo pracować nad kodem. Dlatego to w Twoim interesie jako reviewera (osoby przeglądającej kod) jest zrobienie tego dokładnie. Oczywiście, Twój mentor będzie stanowić drugą linię wsparcia, ale pierwsze uwagi do kodu powinny należeć do Ciebie.

Na czym polega dobre code review?

Samo w sobie code review to nic innego jak analiza kodu i jego odpowiednie komentowanie.

Najczęściej code review składa się z 3 etapów:

1. Manualna weryfikacja – polega na ściągnięciu brancha, który mamy przejrzeć. Musimy na tym etapie dokładnie wiedzieć, jaki jest problem na masterze i jak nowy branch rozwiązuje problem z zadania. W przypadku zakodowania jakiegoś elementu należy sprawdzić, czy dobrze się wyświetla, zrobić testy RWD (o ile dotyczy), a jeśli problem związany jest z JavaScriptem, to sprawdzić pożądane działanie.

Pamiętaj, że celem tego etapu jest sprawdzenie, czy task lub bug został rozwiązany poprawnie, zgodnie z wymaganiami oraz dobrymi praktykami. Nie bój się też posługiwać zdrowym rozsądkiem – np. sprawdź, czy wpisanie nieco dłuższego tekstu nie rozsypie layoutu.

2. Weryfikacja kodu – jeśli uznamy, że rozwiązanie działa tak, jak powinno, to należy sprawdzić, w jaki sposób jest wykonane. I tutaj zazwyczaj zaczynają się schody, ponieważ oczywiste jest to, że im więcej osób, tym więcej pomysłów na rozwiązanie danego problemu. Dlatego musisz sprawdzić istniejące rozwiązanie i pomyśleć, czy jesteś w stanie napisać to prościej, lepiej lub sprytniej. Jeśli tak, to opisz zwoje rozwiązanie.

Korzystaj z interfejsu GitHuba, aby sprawdzić dokładnie jakie zmiany w kodzie są wprowadzone w danym Pull Requeście. Możesz tam również dodawać komentarze do konkretnej linii kodu, dzięki czemu autor Pull Requesta nie będzie musiał zastanawiać się, do czego odnosi się Twoja uwaga.

3. Czyszczenie kodu – jeśli rozwiązanie problemu działa, jest rozwiązane w sposób mądry i prosty, to pozostaje nam sprawdzenie czytelności kodu, czyli jego formatowanie, czy są zachowane wcięcia, czy nazwy zmiennych są jednoznaczne i wszystkiego innego, co wpływa na jakość kodu.

Kiedy kończy się code review?

Code review jest procesem ciągłym. Ktoś tworzy rozwiązanie problemu, wysyła, a Ty sprawdzasz, komentujesz — i znowu, on poprawia, a Ty sprawdzasz i tak do pozytywnego zakończenia. Może to wydawać się trudne na początku, ale z pewnością zaowocuje w przyszłości.

Pamiętaj, że code review nie jest szukaniem winnego ani atakiem na drugą osobę. Staraj się pisać tak, jak Ty chcesz, żeby pisano do Ciebie. Staraj się nie wydawać poleceń, np. "zmień to na...", tylko chociaż czasem zadać pytanie, czy podać sugestię, np. "Czy nie byłoby lepiej zmienić nazwę tej zmiennej na... żeby była podobna do innych?", albo "Ja bym raczej unikał takiego zapisu, bo to może być nieczytelne dla innych. Myślę, że lepiej będzie...".

Zauważ, że w powyższych przykładach pojawia się też uzasadnienie sugestii. To oszczędza wiele czasu, zwłaszcza przy pracy zdalnej, kiedy autor Pull Requesta nie musi pytać "Dlaczego?" i czekać na Twoją odpowiedź.

A co jeśli autor PR-a nie zgadza się z komentarzem?

Na pewno będą się zdarzały takie sytuacje. Pierwszym krokiem jest zawsze rozmowa (nawet w komentarzach na GitHubie) i wymiana poglądów. Jeśli argumenty się wyczerpują, warto również poruszyć tę kwestię na kanale zespołu i porozmawiać z całym zespołem. W ostatecznym podjęciu decyzji oczywiście pomogą Mentorzy i PM.

Zakres dokumentacji projektu zależy od jego skomplikowania. Jeśli zajrzysz np. na dokumentację jQuery, zobaczysz, że jest to potężny zestaw stron, z których można by wydrukować cały podręcznik. Jednak nasz projekt jest bardzo mały, więc i nasza dokumentacja będzie krótka.

Gdzie umieścić dokumentację?

Wszystko, co opisujemy w tym module, może być umieszczone w pliku README.md. Zawartość tego pliku jest automatycznie wyświetlana na stronie repozytorium w GitHubie, tuż pod listą plików. Dzięki temu nie trzeba szukać dokumentacji, a każde sklonowane repozytorium będzie zawierało plik z podstawowymi informacjami dotyczącymi projektu.

Jeśli jednak z ustaleń zespołu wyniknie, że chcecie jakieś zagadnienie opisać dużo dokładniej, możecie do tego wykorzystać jedno z dwóch rozwiązań:

• dodatkowe pliki .md w repozytorium, lub
• Wiki, dostępne w repozytorium GitHuba.

W obu podejściach można umieścić wiele artykułów, a linki do poszczególnych z nich mogą znajdować się w README.md, co usprawni poruszanie się po dokumentacji.

Główną różnicą jest to, że pliki .md będą w repozytorium, a artykuły z Wiki będą dostępne tylko online.

W jakim języku pisać dokumentację?

Standardem jest pisanie dokumentacji po angielsku, z wykorzystaniem formatu Markdown. Za chwilę wyjaśnimy, jak pisać w tym formacie, ale jeśli słyszysz o nim pierwszy raz, nie przejmuj się — pisanie w Markdownie jest bardzo proste!

Z czego powinna się składać każda dokumentacja projektu?

1. Opis projektu – wystarczą 2 zdania, które opisują, co znajduje się w danym repozytorium. W naszym wypadku będzie to informacja, że ten projekt jest przykładową stroną sklepu zakodowaną z darmowego szablonu PSD, w celu nauki kodowania stron.

2. Demo – gdzie można zobaczyć, jak ta strona wygląda? W naszym przypadku będzie to link do strony opublikowanej na GitHub Pages, ale w przypadku np. aplikacji backendowych może to być również link do screenów czy video prezentujących działanie aplikacji.

3. Inicjacja projektu – w jaki sposób rozpocząć pracę nad projektem? Ta część jest zazwyczaj przygotowana dla developerów, którzy dopiero rozpoczynają pracę w projekcie. Warto krok po kroku wyjaśnić:

• co trzeba mieć zainstalowane (np. Node.JS, bo on zawiera NPM) i w jakiej wersji wszystko będzie na pewno działać,
• jak uruchomić instalację paczki (np. npm install),
• jak zbudować wersję produkcyjną, czyli w przypadku strony gotową do opublikowania.

4. Taskery – opis najważniejszych tasków w naszym task runnerze. Nie trzeba opisywać każdego taska, który np. kopiuje pliki .html z jednego katalogu do drugiego. Skupiamy się na tych taskach, które uruchamia developer. Najczęściej będzie to build, watch, i ew. test.

5. Konwencje i dobre praktyki – każdy projekt charakteryzuje się pewnymi konwencjami — np. nazewnictwa klas w HTML, podziału plików .scss na poszczególne komponenty, czy opisu commitów. Warto o tym też napisać, żeby programista, który zaczyna pracę, wiedział dokładnie, czego ma się trzymać.

6. Wykorzystanie – co można zrobić z tym projektem? Warto wspomnieć o customowych sposobach wykorzystania projektu. Przykładem może być sytuacja, jeśli np. stworzyliście kod JS, który sprawdza, czy wrapper slidera ma atrybut data-arrows="true", a jeśli tak, to będą wyświetlane strzałki do przewijania slajdów. A może w prosty sposób można włączyć/wyłączyć synchronizację dwóch sliderów, aby przewijanie jednego przewijało również drugi? Ta część dokumentacji służy właśnie takim tematom. Pamiętaj jednak, że jeśli ta sekcja zacznie za bardzo się rozrastać, może warto przenieść ją do USAGE.md lub do Wiki.

7. Troubleshooting – najczęściej powstające problemy pojawiające się w trakcie pracy nad projektem oraz ich rozwiązania. Przykładem może być np. konieczność uruchamiania task runnera w Git Bashu, jeśli pracuje się na Windowsie.

Dlaczego Markdown?

Jak widzisz, w naszej dokumentacji znajdzie się dość sporo informacji. Warto zadbać o to, aby te informacje były przedstawione w czytelny sposób. Osiągniemy to głównie za pomocą nagłówków oraz list wypunktowanych. Do tego idealnie nadaje się wykorzystywany przez GitHuba (i większość innych platform Gita) format Markdown.

Oczywiście, to nie jest jedyny sposób — można by przecież pisać dokumentację np. w pliku .txt albo nawet w .html. Te sposoby mają jednak swoje problemy — pierwszy z nich będzie mało czytelny, a drugi wymagałby pisania sporej ilości kodu HTML.

Markdown jest językiem znaczników, który umożliwi nam szybkie formatowanie tekstu bez potrzeby używania znaczników HTML. Na stronie GitHuba wyświetli się kod HTML wygenerowany z naszego Markdowna, więc wszystko będzie czytelnie przedstawione, a dla nas pisanie w tym formacie nie będzie zbyt obciążające.

Zacznijmy od trzech podstawowych zasad:

• piszemy w pliku tekstowym z rozszerzeniem .md,
• pomiędzy nagłówkami, paragrafami, etc. wstawiamy pustą linię.

Do tego mamy do dyspozycji szereg znaczników, które będą formatować naszą treść. Spójrz na poniższy przykład tekstu napisanego w języku Markdown:

# Some header 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean bibendum urna id ligula pharetra, vitae iaculis erat maximus.

Praesent nec purus quis turpis facilisis iaculis vel sed dolor. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos.

## Some header 2

1. Morbi ex erat, iaculis eu felis quis, dapibus tempus enim.
2. Ut convallis iaculis nisi, eget imperdiet urna luctus non.
3. Ut ac viverra ex.

### Some header 3

- Donec nec lobortis odio.
- In nec ipsum quis nulla commodo facilisis.

#### Some header 4

> Aliquam auctor nulla eu felis congue, sit amet pulvinar lacus venenatis. Etiam elementum, odio sit amet elementum pellentesque, ex turpis accumsan neque, at egestas nulla tellus vitae mauris.

Powyższy kod wystarczy zapisać w pliku .md, a GitHub wyświetlając ten plik, skonwertuje go na kod HTML, który będzie wyglądał tak:

<h1>Some header 1</h1>

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean bibendum urna id ligula pharetra, vitae iaculis erat maximus.

<p>Praesent nec purus quis turpis facilisis iaculis vel sed dolor. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos.</p>

<h2>Some header 2</h2>

<ol>
  <li>Morbi ex erat, iaculis eu felis quis, dapibus tempus enim.</li>
  <li>Ut convallis iaculis nisi, eget imperdiet urna luctus non.</li>
  <li>Ut ac viverra ex.</li>
</ol>

<h3>Some header 3</h3>

<ul>
  <li>Donec nec lobortis odio.</li>
  <li>In nec ipsum quis nulla commodo facilisis.</li>
</ul>

<h4>Some header 4</h4>

<blockquote>
  <p>Aliquam auctor nulla eu felis congue, sit amet pulvinar lacus venenatis. Etiam elementum, odio sit amet elementum pellentesque, ex turpis accumsan neque, at egestas nulla tellus vitae mauris.</p>
</blockquote>

Dzięki Markdownowi możesz błyskawicznie pisać teksty, które będą odpowiednio sformatowane, bez potrzeby używania skomplikowanego kodu (np. HTML) czy klikania opcji (np. guzika ustawiającego nagłówek 3. stopnia). Co więcej, dokumentacja pisana przez różnych developerów będzie sformatowana dokładnie tak samo, co znacznie ułatwia jej czytanie.

Z powyższego przykładu już zapewne domyślasz się, jak działają podstawowe znaczniki. W następnym rozdziale omówimy kilka najczęściej wykorzystywanych.

Ponieważ większość dokumentów będziemy przygotowywać pod GitHuba, pokażemy Ci znaczniki w nim obowiązujące. Jednak warto pamiętać, że większość interpreterów ma te same rodzaje oznaczeń.

Pełną listę znaczników dla Markdowna w GitHubie znajdziesz tutaj.

Nagłówki

Do stworzenia nagłówka będziemy wykorzystywać znak # przed tekstem nagłówka. W zależności o tego, ile znaków # wpiszemy (od 1 do 6), takiego poziomu będzie nagłówek.

# Nagłówek H1
### Nagłówek H3
###### Nagłówek H6

Ważne - dodaj spację po znakach #, inaczej ta linia nie zostanie zinterpretowana jako nagłówek.

Stylowanie tekstu

• Pogrubienie – **Pogrubiony tekst** lub __Pogrubiony tekst__
• Pochylenie – *Pochylony tekst* lub _Pochylony tekst_
• Przekreślenie – ~~Przekreślony tekst~~
• Pogrubiony z pochyleniem – **Pogrubiony z _pochyleniem_**

Ważne — znaczniki, np. **, muszą przylegać do tekstu. Nie zadziała np. ** oops **.

Cytowanie tekstu

Znak > na początku linii oznacza cytat. Jeśli wiele linii ma należeć do tego samego cytatu, postaw > na początku każdej z nich.

> Every line starting with ">" will be a quote.
> And you can make multi-line quotes by adding ">" to every line,
> (without leaving empty lines between the quoted lines).

Możesz też stosować zagnieżdżone komentarze w ten sposób:

>> older quote
>
> newer quote

Linki

Linki tworzymy poprzez umieszczenie tekstu pomiędzy nawiasami kwadratowymi [ ] oraz podanie linkowanego adresu (href) używając nawiasów okrągłych ( )

Np. [Link do kodilla](https://kodilla.com)

W GitHubie możemy też tworzyć odwołania do innych plików md podając relatywną ścieżkę do nich np. [How to use](docs/USAGE.md).

Obrazki

Dodając obrazek, możemy użyć 3 właściwości - adresu, alt (tekstu alternatywnego) oraz title.

Przykłady:

![alt text](https://adres.pl/logo.png "Title Text")

![alt text](https://adres.pl/logo.png)

![](https://adres.pl/logo.png)

Listy

W Markdownie możemy tworzyć listy numeryczne (ol) lub listy punktowe (ul). Chcąc tworzyć listy wielopoziomowe, musimy pamiętać o zachowaniu odpowiednich wcięć w tekście.

Przykład:

1. Lorem
1. Lorem
1. Lorem

- Lorem
- Lorem
  - Lorem
  - Lorem
    - Lorem

1. Lorem
   - Lorem
   - Lorem
1. Lorem
   - Lorem
   - Lorem

Zwróć uwagę, że tworząc listę wypunktowaną, możemy zawsze wpisać 1. – oczywiście możesz numerować kolejno punkty, ale w wynikowym kodzie HTML to będzie lista numerowana <ol>, więc liczby będą i tak kolejne (1, 2, 3...).

Tabele

Jedną z trudniejszych rzeczy w języku Markdown jest tworzenie właśnie tabeli, ponieważ można je stworzyć w sposób estetyczny lub nieestetyczny. Różnica jest tylko w tym, jak tabela będzie wyglądała bezpośrednio w kodzie Markdown.

Estetyczna tabela nawet w Markdownie wygląda jak tabela, tzn. linie podziału kolumn są proste:

| Column heading    | Column heading    |
| ----------------- | ----------------- |
| Some content      | Another content   |
| Different content | Last content      |

Nieestetyczna tabela zadziała tak samo, ale przez brak dodatkowych odstępów będzie trudniejsza do odczytania w kodzie pliku .md:

| Column heading | Column heading |
| --- | --- |
| Some content | Another content   |
| Different content | Last content |

Obie wersje wygenerują dokładnie ten sam kod HTML tabeli, np.:

Decyzja należy do Ciebie — jeśli chcesz zadbać o czytelność tabeli w kodzie pliku .md, poświęć chwilę czasu na dodanie odpowiednich odstępów.

Bloki kodu

Dodatkowo mamy jeszcze oznaczenia kodu, czyli sposób, w jaki zaznaczamy, że coś jest fragmentem programistycznego kodu.

Takie bloki możemy przedstawiać na dwa sposoby — liniowy i blokowy. W obu przypadkach będziemy używać znaku backtick, czyli `. Na większości klawiatur jest on na tym samym klawiszu co tylda (~), z tym że tylda wymaga wciśnięcia shifta, a backtick nie.

Kod w linii

To jest przykład implementowania zmiennej `var a = 10;`

Rezultat: To jest przykład implementowania zmiennej var a = 10;

Blok kodu w kontenerze

Aby rozpocząć i zakończyć blok kodu, w osobnej linii wpisujemy trzy backticki:

```
<section></section>
```

Rezultat:

<section></section>

Jeśli składnia kodu ma być kolorowana, musisz podać język programowania, dla którego ma zostać użyte kolorowanie. Na przykład:

``` js
var js = 1;
function aaa(){
  return true;
};
```

``` html
<a href="#" class="some-link">Lorem ipsum</a>
```

Ignorowanie formatowania

Jeśli chcesz, aby jakiś symbol był ignorowany, należy przed nim postawić backslash (\).

Np. To jest \*Test\*

Rezultat: To jest *Test*